home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / tbug.arc / TBUG.DOC next >
Encoding:
Text File  |  1986-12-02  |  6.5 KB  |  164 lines
  1.     
  2.              TBUG.SYS - the device driver debugger
  3.                 Copyright (c) 1986 by Communica
  4.                   All rights reserved
  5.  
  6.             
  7.     TBUG.SYS is an MS-DOS installable device driver that addresses
  8.     the old chicken-and-egg problem of how to debug a new device
  9.     driver before DOS is available to load the debugger.  It can
  10.     be activated by hard coding an Interrupt 3 (0CCh) into your
  11.     program at the point you wish the debugger to gain control.
  12.  
  13.     
  14. USAGE AND OPTIONS:
  15.     
  16.     Add the following line to your CONFIG.SYS file immediately
  17.     before the driver you wish to debug.
  18.  
  19.             device = tbug.sys [2] [5] [s]
  20.     
  21.     Where:
  22.     2 enables NMI interception
  23.     5 enables entry via PrtScr key (INT5)
  24.     S forces TBUG to use a local stack instead of the user's stack
  25.     
  26.     NOTE - parameters must be delimited by one or more white spaces.
  27.     
  28.  
  29. OPERATION:
  30.  
  31.     After installation and initialisation, TBUG will display the
  32.     paragraph address that the next device driver will be loaded
  33.     at so all you need to debug your driver is a copy of the link
  34.     map and an understanding of IBM's DEBUG.COM (whose syntax
  35.     TBUG mimics).
  36.  
  37.  
  38. DIFFERENCES FROM IBM'S DEBUG.COM:
  39.     
  40.     TBUG assumes no file system is present so Name, Read, and Write
  41.     commands will not be implemented.  If you need these abilities,
  42.     let me recommend PfixPlus from Phoenix.  If there is enough
  43.     interest, I will implement Sector Read and Sector Write.
  44.     
  45.     Entry via Int 5 will return you to whence you came upon doing
  46.     a 'G' or a 'Q'.  This means that if you do a PrtScr at the
  47.     command prompt, a 'Q' will not appear to return you to the 
  48.     prompt - the cursor will end up sitting at the start of the
  49.     next line.  Type DIR and you'll notice exactly where you are!
  50.     
  51.     The new 'Z' command causes a warm boot by setting the warmboot
  52.     flag in low memory (to prevent memory test) and jumping to
  53.     the cold boot code at F000:FFF0.
  54.     
  55.     Dump has been enhanced - DW, DD, and DA dump as words, dwords, 
  56.     and addresses.
  57.     
  58.     Flags can be modified by using 'R F' or 'R FL'.
  59.  
  60.     TBUG does not wake up with a file size in CX as no file system
  61.     is assumed.
  62.  
  63.     The new B command has been added to do breakpoint maintenance.
  64.     There are two types of breakpoints in TBUG - sticky and temp.
  65.     A temp will interrupt your program and return control to TBUG,
  66.     at this time, ALL temp breakpoints are removed.  Sticky break-
  67.     points will also interrupt the program but TBUG will reenable
  68.     them immediately.  'B' alone  will display all current sticky bps.
  69.     'Bn' will display current location of sticky bp n and
  70.     interactively modify it.  'BRn' will remove sticky breakpoint n.
  71.     'BT' sets a temp (can also be set by 'G seg:ofs').  'BRT seg:ofs'
  72.     will remove temp at seg:ofs while 'BRT' will remove all temps.
  73.     
  74.     Four addresses -  0:0, 0:1, 0:2, and 0:3 - are reserved for
  75.     use as flags in the internal breakpoint tables.  It is not    
  76.     meaningful to set a breakpoint in the reserved interrupt vector
  77.     that is normally found at these addresses.  Breakpoint addresses
  78.     are NOT range checked for these values so you risk invalidating
  79.     the breakpoint identification logic if you attempt to set a
  80.     breakpoint at these addresses!
  81.     
  82.     Also, segment values of 0FFFFh are used internally by the break-
  83.     point setting logic - if for some reason your system does not
  84.     have ROM at the top of the address space, and you need to set 
  85.     a breakpoint in segment F000, avoid using FFFF as a seg address.
  86.  
  87.     'Q' has the same effect as G=cs:ip except that it re-inits 
  88.     internal variables before doing it.  This is because I can't
  89.     assume a file system to do an exit to.  If this behavior is
  90.     not desired, reboot the system with 'Z'.
  91.     
  92.     
  93. CAVEATS:
  94.  
  95.     You must exit via Quit in order to restore ctrl-brk vectors!
  96.     If you use Ctrl-Break to restart the debugger after exiting
  97.     via Go, the system will be in an unstable state and a crash
  98.     is to be expected.  Ctrl-Break interception is only included
  99.     as a method to abort long memory Dumps - not as a hot key.
  100.     If you desire a hot key, use the '5' switch on the command
  101.     line to activate PrtScr as a TBUG entry.
  102.     
  103.     Although stack swapping can be activated by using the 'S' switch,
  104.     this is a questionable practice and is only intended for use
  105.     while debugging TBUG.  Do NOT use this option for normal use!
  106.  
  107.     
  108. DISCLAIMER:
  109.     
  110.     This software is under development - you use it at your own
  111.     risk.  I feel that it can be valuable to any programmer that 
  112.     is writing DOS Installable Device Drivers even in its current
  113.     incomplete state.  As with all such tools, this program has 
  114.     the ability to alter memory while the system is operating and
  115.     cause subsequent failures.  Under no circumstances can the author
  116.     or Communica be held liable for any problems that arise from
  117.     such use.
  118.     
  119.  
  120. LICENSE:
  121.     
  122.     This is a copyrighted program and is not being released into
  123.     the Public Domain, nor is it freeware.  I wrote this because
  124.     I needed a tool that did not exist (unless you consider the
  125.     $45,000 Intel I2ICE machine) in order to do my job.  TBUG
  126.     will be significantly enhanced and distibuted as a commercial
  127.     program.  Plans are to do a bootable ROM implementation with
  128.     write protected RAM so TBUG will work with all PC operating
  129.     systems, not just MS-DOS.
  130.     
  131.     You may use this program in any way that you please and
  132.     distribute it freely as long as it remains un-modified
  133.     and this documentation file is included.
  134.     
  135.     Bug reports and comments are welcome and should be directed to:
  136.     
  137.                 Communica
  138.                 Attn: Matt Trask
  139.                 3 Winslow St.
  140.                 Bourne, MA 02532
  141.  
  142.  
  143. RELEASE NOTES:    
  144.  
  145. Ver 0.1  02/18/86
  146.  
  147.     Not all DEBUG command are implemented at this time - you
  148.     will receive a message to this effect if you try to use
  149.     an unimplemented command.  In particular, Breakpoint is
  150.     documented but not yet activated.  Breakpoints may be set
  151.     but will not be automatically cleared and the old contents
  152.     of the byte where the breakpoint was set will NOT be restored.
  153.  
  154.     Currently supported commands are Dump, Enter, Registers, Go 
  155.     (no G= yet), Trace (also Tn but not T= yet), Quit, 5 (Print
  156.     Screen), and Z (Warmboot).
  157.  
  158.     Stack swapping needs to be enabled with DOS 2.x (not with
  159.     3.x) because the stack provoded by DOS is inadequate.
  160.  
  161.     
  162.  
  163.  
  164.